Integra con IA
Si programas con un asistente de IA (Claude, Codex, Cursor, ChatGPT, Copilot…), aquí tienes el prompt para que integre ZarelaFact en tu software siguiendo esta documentación.
Por defecto, el prompt integra lo que usa la mayoría: la factura de crédito fiscal (31), la de consumo (32) y la nota de crédito (34). El comprobante de compras (41) se agrega si lo pides. Cuando eso funcione, puedes ampliar con webhooks, recibidos o anulaciones (más abajo).
- Abre el asistente en el repositorio de tu ERP o POS.
- Copia el prompt de tu caso con el botón de copiar y pégalo.
- Si tu asistente no abre enlaces, adjúntale el OpenAPI y las páginas que cita el prompt (más abajo).
Antes de pegar nada
- Nunca pegues en el chat una API key, una clave Partner, un secreto de webhook, el
.p12ni su contraseña. El código los lee de variables de entorno; tú los pones en tu.envlocal o en tu gestor de secretos. - Empieza en TesteCF, con una clave
zrl_test_. Si eres Partner, cada cliente tiene su sandbox TesteCF en/fiscal-accounts/{id}/testecf/documents, fuera de tu plan;?validate=truesolo valida, sin enviar a la DGII. - Revisa el código que genere, como el de cualquier persona de tu equipo, y pruébalo antes de llevarlo a producción.
Elige tu caso
- Cuenta directa
- Partner
Para una empresa que integra su propio ERP o POS con su API key (cómo funciona).
Prompt: cuenta directa
Eres un desarrollador senior. Vas a integrar este repositorio, nuestro ERP o POS, con ZarelaFact: la API que emite comprobantes fiscales electrónicos (e-CF) ante la DGII de República Dominicana. Somos una cuenta directa: emitimos con nuestro propio RNC y una API key por ambiente.
Mi proyecto (opcional): <ERP o POS, lenguaje, framework, dónde se registra una venta>
Credencial: la API key está en la variable de entorno ZARELAFACT_API_KEY=<TU_API_KEY de TesteCF>. La pongo yo: nunca me la pidas en el chat ni la escribas en el código, los logs o el frontend.
Qué integrar (si no te digo otra cosa):
- E31 Factura de Crédito Fiscal: venta a una empresa con RNC.
- E32 Factura de Consumo: venta a consumidor final. Envía siempre el documento completo; si es menor de RD$250,000, ZarelaFact manda el resumen (RFCE) a la DGII por nosotros. De RD$250,000 o más lleva el RNC o la identificación del comprador.
- E34 Nota de Crédito: devoluciones, descuentos o correcciones sobre una 31 o una 32 ya aceptada.
- E41 Comprobante de Compras, solo si te lo pido: compras a proveedores que no emiten comprobantes, con sus retenciones.
Nada más por ahora: ni otros tipos de e-CF, ni webhooks, recibidos o anulaciones. Si ves que nuestro negocio los necesita, dímelo y lo vemos aparte.
Antes de escribir código:
1. Lee la documentación. Si no puedes abrir enlaces, pídeme los archivos:
- https://zarelafact.com/docs/llms.txt (índice de toda la documentación)
- https://zarelafact.com/docs/integration/ecf-types (el JSON de cada tipo)
- https://zarelafact.com/docs/openapi.yaml (contrato: rutas, campos y errores)
2. Revisa el repositorio y propón un plan corto. Espera mi visto bueno.
3. No inventes rutas ni campos. Si algo no está en la documentación, pregunta.
Lo esencial de la API:
- URL base: https://api.zarelafact.com/{ambiente}, con ambiente TesteCF (pruebas), CerteCF (certificación) o eCF (producción). Entre ambientes solo cambian la URL y la API key; el ambiente sale de ZARELAFACT_ENVIRONMENT. Header X-API-KEY en cada solicitud.
- Emitir: POST /{ambiente}/documentos-ecf con el JSON del comprobante, en formato DGII (raíz "ECF") o con el contrato simplificado (type, encf, issueDate, buyer, paymentType, incomeType, lines…). Para 31, 32 y 34 el simplificado suele bastar. ?validate=true lo valida sin efectos fiscales.
- El eNCF lo asigna nuestro sistema, del rango que autorizó la DGII, y se guarda con la venta antes de llamar a la API. Ante un timeout o un 5xx, reenvía el mismo JSON con el mismo eNCF: la API no lo duplica.
- 202 significa "en cola", no "aceptado". Para imprimir en caja usa el header "Prefer: wait=10": cuando la DGII responde (TrackID o respuesta del resumen RFCE), el 201 trae result.printing (securityCode, signatureDate, qrUrl) para el ticket o la factura. Antes de esa respuesta no se imprime.
- Estado: POST /{ambiente}/documentos-ecf/status/batch con {"encfs": [...]}. Finales: accepted, accepted_conditional y rejected. Un rechazado no se reenvía: se corrige con un comprobante nuevo.
- Nota de crédito (34): referencia al eNCF original con InformacionReferencia (o reference, con reason, en el simplificado), siempre sobre un comprobante aceptado.
- Errores: un 422 trae el campo exacto en errors[].field: muéstralo y no reintentes igual. Con 429, espera Retry-After. Guarda siempre el correlationId.
Entrega:
1. Un módulo cliente pequeño: validar, emitir y consultar el estado.
2. El mapeo de nuestra venta (y de la devolución, para la 34) al JSON, con pruebas que usen ?validate=true.
3. Configuración por variables de entorno y un .env.example sin valores reales.
4. Pruebas contra TesteCF con secuencias altas, por ejemplo E310009000001: TesteCF es compartido y las bajas ya están usadas. Nunca contra eCF.
Para un ERP, POS o SaaS que emite por varios clientes con la API Partner (cómo funciona).
Prompt: Partner
Eres un desarrollador senior. Vas a integrar este repositorio, nuestro ERP, POS o SaaS, con la API Partner de ZarelaFact, para que cada uno de nuestros clientes emita comprobantes fiscales electrónicos (e-CF) ante la DGII de República Dominicana sin salir de nuestro producto.
Mi proyecto (opcional): <producto, lenguaje, framework, cómo se modelan los clientes>
Credencial: la clave Partner está en la variable de entorno ZARELAFACT_PARTNER_KEY=<TU_CLAVE_PARTNER>. La pongo yo: nunca me la pidas en el chat ni la escribas en el código, los logs o el frontend.
Qué integrar (si no te digo otra cosa):
1. El alta de cada cliente, la carga de su certificado y su certificación ante la DGII, con la pantalla de pasos de ZarelaFact incrustada.
2. La emisión de E31 (crédito fiscal), E32 (consumo) y E34 (nota de crédito sobre una 31 o una 32 aceptada). El E41 (compras a proveedores que no emiten comprobantes, con retenciones) solo si te lo pido.
Nada más por ahora: ni otros tipos de e-CF, ni webhooks, anulaciones, recibidos o aprobación comercial. Si ves que los necesitamos, dímelo y lo vemos aparte.
Antes de escribir código:
1. Lee la documentación. Si no puedes abrir enlaces, pídeme los archivos:
- https://zarelafact.com/docs/llms.txt (índice de toda la documentación)
- https://zarelafact.com/docs/partners/quickstart (el recorrido completo, llamada por llamada)
- https://zarelafact.com/docs/integration/ecf-types (el JSON de cada tipo)
- https://zarelafact.com/docs/openapi.yaml (contrato: rutas /partner/v1, campos y errores)
2. Revisa el repositorio y propón un plan corto. Espera mi visto bueno.
3. No inventes rutas ni campos. Si algo no está en la documentación, pregunta.
Lo esencial de la API Partner:
- URL base: https://api.zarelafact.com/partner/v1. Una sola clave para todos los clientes, en el header X-PARTNER-KEY, que vive solo en el backend: nunca en el navegador, la app ni el POS. Cada cliente tiene un sandbox TesteCF: POST /fiscal-accounts/{id}/testecf/documents envía la factura de prueba al ambiente de pruebas de la DGII con su certificado, sin activación ni plan (no cuenta en el plan; usa secuencias altas como E310009000001). La certificación corre en CerteCF y la emisión real en eCF.
- Cliente: PUT /fiscal-accounts/by-external-id/{externalTenantId} con {"rnc", "legalName"}. Se puede repetir sin duplicar. Guarda el fiscalAccountId junto a nuestro ID del cliente.
- Certificado: el .p12 y su contraseña nunca pasan por nuestro backend. POST /fiscal-accounts/{id}/certificate-upload-sessions con {"browserOrigin": "<origen HTTPS de nuestra UI, de la configuración>"} devuelve uploadUrl y uploadToken, y el navegador sube el archivo directo a ZarelaFact (PUT multipart con file y passphrase, header "Authorization: Upload <uploadToken>").
- Certificación: POST /fiscal-accounts/{id}/certification-sessions con {"browserOrigin"} devuelve una url para mostrar en un iframe. Pide una nueva cada vez que el usuario abra la pantalla.
- Producción se activa sola al aprobarse la certificación: consulta GET /fiscal-accounts/{id}/production y no dejes emitir mientras no esté activa.
- Emitir: POST /fiscal-accounts/{id}/production/documents con {"document": <JSON>}, en formato DGII (raíz "ECF") o con el contrato simplificado, y el RNC del cliente como emisor. Con "Prefer: wait=10", el 201 trae result.printing (securityCode, signatureDate, qrUrl) para imprimir en cuanto la DGII responde. 202 significa "en cola", no "aceptado".
- El eNCF lo asigna nuestro sistema, del rango de ese cliente, y se guarda con la venta antes de llamar. Ante un timeout, reenvía el mismo JSON con el mismo eNCF: la API no lo duplica.
- Estado: POST /fiscal-accounts/{id}/production/documents/status/batch con {"documentIds": [...]}. Finales: accepted, accepted_conditional y rejected. Un rechazado no se reenvía: se corrige con un comprobante nuevo.
- Nota de crédito (34): referencia al eNCF original con InformacionReferencia (o reference, con reason, en el simplificado), siempre sobre un comprobante aceptado.
- Errores: 400 INVALID_PARTNER_PAYLOAD es un campo desconocido o mal tipado (omite los opcionales, no envíes null). Un 422 trae el campo exacto en errors[].field. 402 PAYMENT_REQUIRED: no reintentes. Con 429, espera Retry-After. Guarda siempre el correlationId.
Entrega:
1. Un módulo cliente pequeño para /partner/v1: cuenta fiscal, sesiones de certificado y de certificación, estado de producción, validar, emitir y consultar el estado.
2. Tablas o migraciones: cliente con externalTenantId y fiscalAccountId, y cada venta con su eNCF, su JSON, su documentId y su estado.
3. Configuración por variables de entorno (ZARELAFACT_PARTNER_KEY, ZARELAFACT_BROWSER_ORIGIN) y un .env.example sin valores reales.
4. Pruebas contra el sandbox TesteCF de un cliente de prueba (/testecf/documents) o con ?validate=true y un cliente HTTP simulado. Nada de emitir en eCF desde pruebas.
Amplía cuando lo necesites
Cuando la emisión funcione en TesteCF (si eres Partner, en el sandbox /testecf/documents de un cliente), agrega lo demás de a una cosa a la vez, en la misma conversación:
Prompt: amplía la integración
Agrega a nuestra integración con ZarelaFact: <lo que necesitas>. Sigue esta página de la documentación: <URL de la tabla>. Mantén lo que ya funciona y las mismas reglas: nada de credenciales en el código, el mismo eNCF en cada reintento y pruebas sin emitir en eCF. Propón el plan antes de escribir código.
| Qué agregar | Cuenta directa | Partner |
|---|---|---|
| Comprobante de compras (41) u otro tipo (33, 43 a 47) | /integration/ecf-types | La misma página |
| Webhooks: avisos de cambio de estado en lugar de consultar | /integration/webhooks | /partners/webhooks |
| Descargar el XML firmado y el PDF | /integration/printed-representation | /partners/production |
| Documentos recibidos y aprobación comercial | /integration/commercial-approval | /partners/production |
| Anular eNCF no usados (ANECF) | /integration/annulments | /partners/production |
Revisa una integración que ya tienes
Para que el asistente audite tu código contra esta documentación, sin cambiar nada:
Prompt: revisa mi integración
Revisa la integración con ZarelaFact de este repositorio contra la documentación oficial. Lee primero https://zarelafact.com/docs/llms.txt y https://zarelafact.com/docs/openapi.yaml. Si no puedes abrir enlaces, pídeme los archivos. No cambies código todavía.
Revisa solo lo que la integración usa (por ejemplo, si no hay webhooks, sáltate ese punto). Comprueba y reporta, con archivo y línea:
1. Que ninguna API key, clave Partner, secreto de webhook, .p12 o contraseña esté en el código, en logs, en el frontend ni en el repositorio: todo sale del entorno o de un gestor de secretos.
2. Que las rutas, los headers (X-API-KEY o X-PARTNER-KEY, Prefer, Idempotency-Key) y los campos coincidan con el OpenAPI.
3. Que el eNCF se asigne y se guarde antes de llamar a la API, y que un reintento reenvíe el mismo JSON con el mismo eNCF, nunca uno nuevo ni un JSON regenerado.
4. Que 202 (en cola) y 201 (firmado) no se traten como aceptados, y que el estado se concilie por lote hasta accepted, accepted_conditional o rejected.
5. Que 400, 401, 402, 403, 409, 422, 423, 429 (con Retry-After), 5xx y timeouts se manejen como indica la documentación, y que se guarde el correlationId.
6. Si hay receptor de webhooks, que verifique Zarela-Signature con el cuerpo crudo, acepte dos v1, rechace timestamps de más de 5 minutos y deduplique por Zarela-Event-Id.
7. Que los documentos en contingency o rejected no se reenvíen ni se anulen por error.
8. Que las pruebas usen TesteCF o ?validate=true y nunca emitan en eCF.
Entrega una lista por prioridad (crítico, importante, menor), con la corrección que propones y el enlace a la página de la documentación que la respalda.
Dale contexto a tu IA
Estos enlaces sirven para cualquier asistente. Si no navega por Internet, descárgalos y adjúntalos.
| Recurso | Para qué |
|---|---|
https://zarelafact.com/docs/llms.txt | Índice de esta documentación pensado para IA: cada página con su URL y de qué trata. |
https://zarelafact.com/docs/openapi.yaml | El contrato exacto: rutas, campos, respuestas y errores de la API directa y de la API Partner. |
| Formato JSON de e-CF y Ejemplos JSON por tipo | Cómo armar el JSON de cada tipo de comprobante. |
| Envío y Consulta | Emisión, idempotencia, estados y errores de la cuenta directa. |
| Qué construir en tu ERP y Rutas y errores | Pantallas, datos y todas las rutas de la API Partner. |
Si tu asistente lee reglas del proyecto (por ejemplo CLAUDE.md, AGENTS.md o las reglas de Cursor), agrega ahí los dos primeros enlaces para que los tenga en cada sesión.
Siguiente: Autenticación API.