Find a proforma by external ID
Look up a single proforma by its external_id (sent in the JSON body), the integration key that maps it to a record in a third-party system (ERP/CRM/e-commerce). Returns the matching proforma or 404 proforma_not_found if no proforma uses that external_id within your company.
Request
- Base URL: https://api.factuarea.com/v1
- URL: https://api.factuarea.com/v1/companies/{company}/proformas/find-by-external-id
- Auth: one of:
- HTTP bearer
- API key in header X-API-Key
Path parameters
Public identifier (UUID v7) of the company. Get it from GET /v1/me (data.scope[].id).
Headers
Pin the API version (YYYY-MM-DD, Stripe-style date versioning) for this request; omit to use the key's pinned version, or the latest if none. Unsupported version → 400 unsupported_api_version; malformed → 400 parameter_invalid_format. The effective version is echoed in the Factuarea-Version response header. See the Versioning guide.
Request body
Response
Example response
{
"data": {
"id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a05",
"object": "proforma",
"number": "PRO-2026-00007",
"series": {
"id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e",
"code": "F-2026"
},
"client": {
"id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",
"name": "Acme Corporation"
},
"status": "draft",
"issued_on": "2026-01-22",
"valid_until": "2026-02-21",
"validity_days": 30,
"reference": "REF-API-2026-001",
"operation_regime": "general",
"converted_invoice_number": "F-2025-003",
"subtotal": "1500.00",
"taxes_total": "315.00",
"total_vat": "315.00",
"total_retention": "0.00",
"total_surcharge": "0.00",
"total": "1815.00",
"shipping_cost": "15.50",
"total_with_shipping": "1830.50",
"currency": "EUR",
"payment_method": "bank_transfer",
"payment_terms_days": 30,
"delivery_terms": "Entrega en 5 dias habiles, portes incluidos",
"estimated_delivery_date": "2026-06-10",
"notes": "Proforma pendiente de validación.",
"terms_and_conditions": "Validez 30 dias. Proforma sin valor fiscal hasta su conversion en factura.",
"external_id": "ERP-PRO-2026-0007",
"lines": [
{
"description": "Setup inicial",
"additional_description": "Auditoría inicial e informe de mejoras",
"product": {
"id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09",
"name": "Consultoría hora estándar"
},
"quantity": 1,
"unit_price": "1500.0000",
"tax_rate": 21,
"subtotal": "1500.00",
"taxes": "315.00",
"total": "1815.00",
"counted_quantity": "4.0000",
"configuration": {
"id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c03",
"name": "Setup · In situ",
"signature": "e2704ac1936bd85f0c4a71e2853d69b0fa17c4e6d92038b5417ec0a6395d8b12"
},
"options": [
{
"group": {
"id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c13",
"name": "Modalidad"
},
"value": {
"id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c23",
"name": "In situ"
},
"price_adjustment": "250.0000",
"applied": true
}
],
"price_semantics": "per_commercial_unit",
"price_adjustment_total": "250.0000"
}
],
"metadata": {
"erp_code": "IVA-GEN",
"ledger_account": "477000"
},
"tags": [
"exportacion",
"pendiente-validar"
],
"custom_fields": [
{
"field": "incoterm",
"value": "EXW"
}
],
"link_expires_at": "2026-07-01T09:53:23+02:00",
"link_is_active": true,
"created_at": "2026-01-22T09:10:00Z",
"updated_at": "2026-01-22T09:10:00Z"
}
}Changes
No recorded changes to this operation across all 1 revision of this API.