Consulta de documentos

Como el procesamiento es asincrono, consultas el estado final de tus documentos despues de emitirlos. Zarela ofrece una consulta por lote optimizada para sincronizar muchos documentos a la vez.

Consulta por lote (status batch)

POST /{environment}/documentos-ecf/status/batch

Requiere el scope status:read.

Encabezados

X-API-KEY: {api_key_del_ambiente}
Content-Type: application/json

Limites

• Maximo: 100 documentos por solicitud.
• Recomendado: 50 por lote con backoff entre llamadas.

Cuerpo

Puedes consultar por encfs o por documentIds:

{ "encfs": ["E310000000010", "E340000000001"] }

{ "documentIds": ["6f89c3d2-5f83-4607-9b50-99527cc40e5a"] }

Ejemplo

curl -X POST \
  https://ecf.api.zarela.do/TesteCF/documentos-ecf/status/batch \
  -H 'X-API-KEY: zk_test_...' \
  -H 'Content-Type: application/json' \
  -d '{ "encfs": ["E310000000010", "E340000000001"] }'

async function consultarLote(encfs) {
  const response = await fetch(
    "https://ecf.api.zarela.do/TesteCF/documentos-ecf/status/batch",
    {
      method: "POST",
      headers: {
        "X-API-KEY": process.env.ZARELA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ encfs }),
    }
  );
  return await response.json();
}

<?php
function consultarLote($encfs, $apiKey) {
    $ch = curl_init('https://ecf.api.zarela.do/TesteCF/documentos-ecf/status/batch');
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'X-API-KEY: ' . $apiKey,
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS => json_encode(['encfs' => $encfs]),
    ]);
    $result = curl_exec($ch);
    curl_close($ch);
    return json_decode($result, true);
}

Respuesta

{
  "ok": true,
  "count": 2,
  "recommendedBatchSize": 50,
  "maxBatchSize": 100,
  "results": [
    {
      "documentId": "6f89c3d2-5f83-4607-9b50-99527cc40e5a",
      "encf": "E310000000010",
      "status": "accepted",
      "dgiiStatus": "Aceptado",
      "trackId": "0cc42712-4a99-48be-b66d-346b33e36d7f",
      "messages": []
    },
    {
      "encf": "E340000000001",
      "status": "rejected",
      "dgiiStatus": "Rechazado",
      "trackId": "32c4f7e0-dbbe-40cc-a1d4-e4cc0ff82c13",
      "messages": [
        "El campo MontoGravadoTotal del area Totales de la seccion Encabezado..."
      ]
    }
  ]
}

Campos de cada resultado

Campo	Descripcion
documentId	Identificador interno de Zarela.
encf	Numero de comprobante consultado.
status	Estado interno: queued_for_signing, signed, rfce_pending_dispatch, sent, pending_dgii_status, accepted, accepted_conditional, rejected, contingency, cancelled. Ver estados del documento.
dgiiStatus	Estado reportado por la DGII (texto).
trackId	TrackID de la DGII para trazabilidad.
messages	Mensajes/observaciones de la DGII (si aplica).

Recomendaciones de uso

• Agrupacion inteligente: agrupa por periodo o proceso.
• Tamano de lote: usa grupos de ~50 para mejor rendimiento.
• Consultas programadas: ejecuta el batch de forma periodica con backoff.
• Cache local: guarda los resultados finales (accepted, accepted_conditional y rejected) para evitar consultas repetidas.
• No re-consultes estados finales: una vez accepted, accepted_conditional o rejected, el estado fiscal no cambia.

Reconciliacion automatica

Zarela tambien ejecuta una reconciliacion nocturna que actualiza estados pendientes contra la DGII. Aun asi, tu integracion debe consultar el batch para reflejar el estado en tu sistema.

Documentos en contingencia

Si la DGII esta degradada o caida, los documentos quedan en estado contingency y Zarela los reintenta automaticamente. Puedes listarlos para monitoreo:

GET /{environment}/contingencia

Requiere el scope status:read. No necesitas hacer nada con estos documentos: al restablecerse la DGII, Zarela los envia y su estado avanza normalmente (lo veras reflejado en el batch).