{
"event": "document.created",
"timestamp": "2024-04-14T10:00:00Z",
"data": {
"reference": "aaea7db4-647c-4d92-9f86-89e34a68e1aa",
"beneficiary": {
"reference": "616263a5-a677-4ad1-92ca-7e120adad8d4",
"origin": "fiscal",
"name": "Proveedor Ejemplo S.A.S",
"identifier_type": "NIT",
"identifier_number": "900123456",
"is_deleted": false,
"deleted_at": null,
"contact_information": []
},
"document_number": "FC-2024-001",
"type": "invoice",
"issue_date": "2024-04-14",
"expiration_date": "2024-04-30T10:00:00Z",
"fiscal_reference": "e19d3e7867371a12fd53b67a56db087faa871c9797993d9bbf7806ae4e1466ea",
"fiscal_metadata": {
"final_notes": "Factura sujeta a retención en la fuente según artículo 383 del E.T."
},
"amount": 1190000,
"amount_currency": "COP",
"status": "pending",
"payment_status": "pending",
"file_path": "https://storage.payana.cloud/documents/FC-2024-001.pdf",
"is_archived": false,
"purchase_order": "OC-2024-001",
"tags": [],
"created_at": "2024-04-14T10:00:00Z",
"updated_at": "2024-04-14T10:00:00Z"
}
}Webhooks
Document Created
Se envía cuando un nuevo documento es creado en Payana (por sincronización con la DIAN/SAT o carga manual). El payload incluye la referencia interna de Payana (reference), la referencia fiscal (fiscal_reference) y, cuando aplica, fiscal_metadata (hoy final_notes desde las notas UBL cbc:Note del XML).
- Para marcar el documento como admitido en Payana (tag
admitido, sin cambiar aprobación):POST /documents/{reference}/acknowledge. - Para aprobar el documento en el flujo de Payana:
POST /documents/{reference}/approve(el path acepta UUID de Payana o CUFE / referencia fiscal).
El receptor del webhook debe responder con 200 para confirmar la recepción del evento.
WEBHOOK
document.created
{
"event": "document.created",
"timestamp": "2024-04-14T10:00:00Z",
"data": {
"reference": "aaea7db4-647c-4d92-9f86-89e34a68e1aa",
"beneficiary": {
"reference": "616263a5-a677-4ad1-92ca-7e120adad8d4",
"origin": "fiscal",
"name": "Proveedor Ejemplo S.A.S",
"identifier_type": "NIT",
"identifier_number": "900123456",
"is_deleted": false,
"deleted_at": null,
"contact_information": []
},
"document_number": "FC-2024-001",
"type": "invoice",
"issue_date": "2024-04-14",
"expiration_date": "2024-04-30T10:00:00Z",
"fiscal_reference": "e19d3e7867371a12fd53b67a56db087faa871c9797993d9bbf7806ae4e1466ea",
"fiscal_metadata": {
"final_notes": "Factura sujeta a retención en la fuente según artículo 383 del E.T."
},
"amount": 1190000,
"amount_currency": "COP",
"status": "pending",
"payment_status": "pending",
"file_path": "https://storage.payana.cloud/documents/FC-2024-001.pdf",
"is_archived": false,
"purchase_order": "OC-2024-001",
"tags": [],
"created_at": "2024-04-14T10:00:00Z",
"updated_at": "2024-04-14T10:00:00Z"
}
}Antes de procesar el evento, verifica la firma HMAC del request. Consulta Signature Verification en la introducción de la API.
Authorizations
API key provista por Payana.
Headers
Allowed value:
"document.created"Body
application/json
Webhook payload
Response
200
Return 200 to acknowledge receipt