# Cómo funciona

> Entornos, llaves, varios clientes y estados, en una página.

**En resumen**
- Cambias de entorno cambiando la llave, no el código.
- Cada e-CF lleva una clave tuya (`Idempotency-Key`): repetirla nunca emite dos veces.
- La DGII responde en segundos: te avisamos o consultas gratis.

> Borrador v0 (16/11/2026): la API todavía no está abierta y las rutas y los nombres pueden cambiar.

## Entornos

| Entorno | Para qué | Llave |
| --- | --- | --- |
| TesteCF | Desarrollo y pruebas. Sin validez fiscal. | `num_test_…` |
| CerteCF | Las pruebas que pide la DGII antes de que tu cliente emita. Te guiamos. | `num_test_…` |
| eCF | Producción: comprobantes reales. | `num_live_…` |

Tu código es el mismo en los tres. Solo cambia la llave.

## Llaves de API

- Las creas en tu panel (muy pronto). Se ven una sola vez.
- Van en el encabezado `Authorization: Bearer num_test_…`.
- Guárdala en tu servidor, nunca en una app ni en el navegador.

## Varios clientes

- Tu cuenta agrupa a tus clientes. Cada uno es una empresa con su RNC y su certificado digital (.p12).
- La ruta lleva el RNC: `/v1/empresas/{rnc}/ecf`. Ningún cliente ve los documentos de otro.
- Una sola factura al mes, con una línea por empresa.

## El recorrido

1. **Validas** el JSON con `POST /v1/validar`. No necesita certificado digital ni gasta nada.
2. **Envías** el e-CF con tu `Idempotency-Key`. Responde `202` con el estado `recibida`.
3. **Lo revisamos**, lo firmamos con el certificado digital de tu cliente y lo enviamos a la DGII.
4. **La DGII responde** en segundos. Te avisamos por webhook, o consultas el estado.
5. **Descargas** el XML firmado y el PDF.

**Enviar un e-CF**

cURL

```bash
curl https://api.numetria.com/v1/empresas/999000001/ecf \
  -H "Authorization: Bearer $NUMETRIA_LLAVE" \
  -H "Idempotency-Key: venta-1042" \
  -H "Content-Type: application/json" \
  -d @e32.json
```

JavaScript

```js
const respuesta = await fetch('https://api.numetria.com/v1/empresas/999000001/ecf', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.NUMETRIA_LLAVE}`,
    'Idempotency-Key': 'venta-1042',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(ecf),
})
const resultado = await respuesta.json()
```

PHP

```php
$ch = curl_init('https://api.numetria.com/v1/empresas/999000001/ecf');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('NUMETRIA_LLAVE'),
        'Idempotency-Key: venta-1042',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($ecf),
]);
$resultado = json_decode(curl_exec($ch), true);
```

C#

```csharp
using var cliente = new HttpClient();
var solicitud = new HttpRequestMessage(HttpMethod.Post, "https://api.numetria.com/v1/empresas/999000001/ecf")
{
    Content = new StringContent(json, Encoding.UTF8, "application/json"),
};
solicitud.Headers.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("NUMETRIA_LLAVE"));
solicitud.Headers.Add("Idempotency-Key", "venta-1042");
var respuesta = await cliente.SendAsync(solicitud);
var resultado = await respuesta.Content.ReadAsStringAsync();
```

Python

```python
import os, requests

respuesta = requests.post(
    "https://api.numetria.com/v1/empresas/999000001/ecf",
    headers={
        "Authorization": f"Bearer {os.environ['NUMETRIA_LLAVE']}",
        "Idempotency-Key": "venta-1042",
    },
    json=ecf,
)
resultado = respuesta.json()
```

**Respuesta · 202**

```json
{
  "encf": "E320000000001",
  "estado": "recibida",
  "entorno": "pruebas"
}
```

**Al consultar, unos segundos después**

```json
{
  "encf": "E320000000001",
  "estado": "aceptada",
  "entorno": "pruebas",
  "documentos": {
    "xml": "/v1/empresas/999000001/ecf/E320000000001/xml",
    "pdf": "/v1/empresas/999000001/ecf/E320000000001/pdf?formato=rollo"
  }
}
```

## Estados

| Estado | Qué significa | ¿Final? |
| --- | --- | --- |
| `recibida` | Lo tenemos y lo estamos revisando. | No |
| `no-pasa-la-revision` | Tiene errores. No se firmó ni se gastó la secuencia. | Sí |
| `enviada` | Firmado y en la DGII. | No |
| `aceptada` | La DGII lo aceptó. | Sí |
| `aceptada-condicional` | La DGII lo aceptó con observaciones. | Sí |
| `rechazada` | La DGII lo rechazó. El motivo viene en la respuesta. | Sí |

## Validar antes de enviar

Si algo no pasa la revisión, te decimos qué campo es y por qué:

**POST /v1/validar · 200**

```json
{
  "listo": false,
  "hallazgos": [
    {
      "codigo": "sumas.monto-total",
      "severidad": "condicional",
      "ruta": "ECF/Encabezado/Totales/MontoTotal",
      "mensaje": "MontoTotal no cuadra con MontoGravadoTotal + MontoExento + TotalITBIS: la diferencia es 92. La DGII lo recibiría como «Aceptado Condicional»."
    }
  ],
  "erroresXsd": [
    {
      "ruta": "ECF/Encabezado/IdDoc/FechaVencimientoSecuencia",
      "mensaje": "falta: es obligatorio"
    }
  ]
}
```

## Idempotencia

- Manda una clave tuya en `Idempotency-Key`: el número de tu venta, por ejemplo.
- Misma clave y mismo JSON: te devolvemos lo mismo, sin emitir otra vez.
- Misma clave y otro JSON: error `409`.
- No uses el e-NCF como clave.

## Gratis

- Todo en TesteCF y en CerteCF.
- Validar tu JSON (`POST /v1/validar`).
- Consultar el estado, las veces que quieras.
- Los avisos (webhooks) de cada cambio de estado.
- El XML firmado y el PDF, en carta o en rollo de 80 mm.
- Los e-CF que te envían otras empresas.
- Los rechazados por la DGII.

Solo se cobra lo que la DGII acepta en producción. [Ver precios](https://developers.numetria.com/precios)
