# Introducción

> API del gateway de facturación electrónica (CFE) de pymo

El gateway es el componente de pymo que habla con DGI: firma, envía y consulta
comprobantes fiscales electrónicos (CFE) de Uruguay. Esta documentación cubre la
superficie pública para integradores - emisión, consulta, recepción y referencia.

## Convención de respuesta

Todas las respuestas JSON comparten esta forma:

```json
{
  "payload": { },
  "message": { "code": "DGI_CFES_RECEIVE_SUCCESS", "value": "Cfes recibidos correctamente." },
  "status": "SUCCESS"
}
```

- `status`: `SUCCESS` o `FAIL`
- `message.code`: código estable para decidir programáticamente
- `payload`: los datos

<Warning>
No alcanza con el HTTP status: hay operaciones que devuelven `200` con
`status: "FAIL"` en el body. Evaluar siempre `status` y `message.code`.
</Warning>

## Cómo empezar

1. [Ambientes y URLs base](/ambientes)
2. [Autenticación](/autenticacion)
3. [Emitir un CFE](/emision)

## Cuándo parar y preguntar

Esta documentación describe **la API**: qué endpoints hay, qué se manda, qué
vuelve y qué garantiza el gateway. No describe **el régimen fiscal uruguayo**, y
la diferencia importa porque los dos aparecen mezclados en el mismo request.

La regla, para una persona y sobre todo para un agente que escriba la
integración: si el dato es fiscal y acá no está dicho, **no lo deduzcas**. Un CFE
emitido con el criterio equivocado no es un bug que se arregla con un fix: es un
documento fiscal ante DGI, consume numeración y sólo se compensa con otro
comprobante.

Cosas que **no** están definidas acá y no hay que inventar:

| Pregunta | Dónde se contesta |
|---|---|
| Qué tipo de CFE corresponde a una operación | Régimen fiscal / contador de la empresa |
| Qué `IndFact` lleva cada línea | [Formato CFE](https://www.efactura.dgi.gub.uy/principal/ampliacion_de_contenido/documento-de-formato-cfe-version-23-1) de DGI |
| Cómo se trata un impuesto o una exoneración concreta | DGI, o el contador |
| Qué campos de receptor exige un tipo y monto | [Formato CFE](https://www.efactura.dgi.gub.uy/principal/ampliacion_de_contenido/documento-de-formato-cfe-version-23-1) de DGI |
| Cómo redondear cuando el total no cierra | Ver [Reglas fiscales](/reglas-fiscales); lo que no esté ahí, DGI |
| Si corresponde anular o emitir una nota de crédito | Contador; la mecánica está en [Emisión](/emision) |
| Cuándo se puede usar contingencia | Ver [Contingencia](/contingencia); el criterio es de DGI |

Señales de que estás por adivinar, y conviene frenar:

- Estás eligiendo entre dos códigos DGI porque "el otro dio error".
- Estás ajustando un monto para que el comprobante sea aceptado.
- Estás copiando un ejemplo de otro tipo de CFE porque el tuyo no está documentado.
- Vas a emitir en producción para ver qué pasa.

Lo barato es preguntar antes. Lo caro es después: los comprobantes de prueba en
producción existen para siempre.

### Si estás construyendo esto con un agente

La regla de arriba vale igual, pero hace falta decirla como condición de parada,
porque un agente al que se le pide "que la factura salga" va a completar el campo
que falte antes que detenerse:

> **Si un campo del CFE no está documentado acá y no está resuelto en el documento
> Formato CFE de DGI que tengas a mano, no lo completes. Pará y preguntá.**

Concretamente, un agente **no** debería:

- elegir un `IndFact` porque el otro dio error;
- inventar un `TipoDocRecep` o un código de retención;
- ajustar montos hasta que DGI acepte;
- emitir en producción para ver qué pasa.

Y si no tiene acceso al documento de DGI, esa es en sí misma la señal de parada:
la estructura del request está acá, el significado fiscal de cada campo no.

Esa regla y el resto de esta documentación vienen empaquetadas como skill, para que
el agente las tenga cargadas antes de escribir la primera línea: ver
[Skill para agentes](/skill-para-agentes).