> ## Documentation Index
> Fetch the complete documentation index at: https://www.emissa.com.ar/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart: de cero a un comprobante

> Cuatro pedidos HTTP: emitir con CAE real, consultar, bajar el PDF y anular. Cada comando de la guía se ejecutó.

Al final de esta guía vas a tener un comprobante **con CAE de ARCA**, su PDF, y
la anulación hecha. Cuatro pedidos HTTP.

> [!NOTE]
>
> Todo lo que sigue —cada comando y cada respuesta— **se ejecutó**. Las
> respuestas son las que devolvió la API, sin retocar. Corrieron contra
> **homologación**, que es el entorno donde vas a empezar y donde ARCA entrega
> **CAE real**: no es un simulador.

## Antes de empezar: lo que Emissa no te puede dar

Para emitir contra ARCA hacen falta tres cosas, y **dos son trámites tuyos ante
el organismo**:

| Qué hace falta | ¿Lo resuelve Emissa? |
| - | - |
| Un **certificado de ARCA** con su clave privada | No — se pide en el sitio de ARCA |
| Un **punto de venta** para «Factura Electrónica – Webservice» | No — es un alta en ARCA |
| Una cuenta de Emissa con una **API key** | Sí, en el panel |

> [!WARNING]
>
> **Sé honesto con el reloj.** Si ya tenés el certificado y el punto de venta,
> lo que sigue son cinco minutos. Si no los tenés, el trámite ante ARCA es la
> parte larga y no depende de nosotros.

El punto de venta tiene su vuelta: el alta del portal web **no sirve** para
emitir por API. Está en [Qué es un punto de venta](https://www.emissa.com.ar/docs/guias/punto-de-venta.md).

## 1 · La clave

Esto se hace **en el panel, con el navegador**. El alta de cuenta y la creación de
claves son del panel a propósito, porque entregar una credencial de integración es
de lo más sensible que hace el sistema.

**1. Creá tu cuenta y verificá el correo**

En [emissa.com.ar](https://www.emissa.com.ar).

**2. Activá el segundo factor**

No es opcional: sin 2FA no se pueden crear API keys.

**3. Cargá tu contribuyente**

CUIT, razón social, condición frente al IVA, punto de venta y domicilio.

**4. Subí el certificado y su clave privada**

Emissa los guarda cifrados. El panel nunca vuelve a mostrar la clave
privada.

**5. Generá una API key de prueba**

Empieza con `emi_test_`. **Se muestra una sola vez** — guardala en tu gestor
de secretos.

### El otro dato que vas a necesitar

Cada emisión pide el id de tu contribuyente, y **no es el CUIT**: es el id que
Emissa le dio. Se obtiene con la clave que acabás de crear:

```bash theme={null}
curl https://api.emissa.com.ar/v1/consumo -H "X-API-Key: $EMISSA_API_KEY"
```

```json theme={null}
{
  "taxpayers": [
    {
      "taxpayerId": "cms6q9ym80008ureocwo81ig2",
      "cuit": "20437136697"
    }
  ]
}
```

Ese `taxpayerId` es el que va en el cuerpo de la emisión. Alcanza con una clave
que declare `invoice:read` — verificado con una clave que **sólo** tenía ese
scope.

## 2 · Emitir

Una Factura B a consumidor final por \$1.000 + IVA.

```bash theme={null}
curl -X POST https://api.emissa.com.ar/v1/invoices/authorize \
  -H "X-API-Key: $EMISSA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-6.1-primera" \
  -d '{
    "taxpayerId": "TU_TAXPAYER_ID",
    "cbteTipo": 6,
    "concepto": 1,
    "receiverDocTipo": 99,
    "receiverDocNro": "0",
    "receiverName": "Consumidor Final",
    "receiverVatConditionId": 5,
    "issueDate": "2026-07-29",
    "items": [
      {
        "description": "Plan Pro - julio 2026",
        "unit": "UNIDADES",
        "quantity": 1,
        "unitPrice": 1000,
        "tratamiento": "GRAVADO",
        "vatRateId": 5
      }
    ]
  }'
```

`201 Created`, en 7,1 segundos. Lo importante de la respuesta:

```json theme={null}
{
  "comprobante": "0001-00000131",
  "status": "AUTHORIZED",
  "cae": "86300696468093",
  "caeExpiresAt": "2026-08-08",
  "totals": {
    "netAmount": "1000.00",
    "vatAmount": "210.00",
    "totalAmount": "1210.00"
  }
}
```

> [!TIP]
>
> **Eso es un comprobante fiscal.** El `cae` y su vencimiento los emitió ARCA,
> no Emissa.

> [accordion] La respuesta completa
>
> ```json theme={null}
> {
>   "id": "cms6l4gnq0007ur04xl1dcqf0",
>   "environment": "HOMOLOGACION",
>   "cbteTipo": 6,
>   "cbteTipoNombre": "FACTURA_B",
>   "letra": "B",
>   "salePoint": 1,
>   "number": 131,
>   "comprobante": "0001-00000131",
>   "issueDate": "2026-07-29",
>   "totals": {
>     "netAmount": "1000.00",
>     "nonTaxedAmount": "0.00",
>     "exemptAmount": "0.00",
>     "vatAmount": "210.00",
>     "otherTaxesAmount": "0.00",
>     "totalAmount": "1210.00"
>   },
>   "vatBreakdown": [
>     {
>       "vatRateId": 5,
>       "vatRatePercent": 21,
>       "baseAmount": "1000.00",
>       "vatAmount": "210.00"
>     }
>   ],
>   "status": "AUTHORIZED",
>   "cae": "86300696468093",
>   "caeExpiresAt": "2026-08-08",
>   "arcaMetadata": {
>     "service": "wsfev1",
>     "resultado": "A",
>     "authorized": true,
>     "observaciones": 0
>   }
> }
> ```
>
> Recortado: la respuesta trae además `emitter`, `receiver`, `items`, `customer`,
> `taxes`, `associations`, `optionals` y `observations`. Los campos de arriba son
> textuales.
>
> Los importes viajan como **string**, no como número: `"1210.00"`. Es a
> propósito —un `float` no representa pesos— y tu cliente HTTP no tiene que
> redondear nada.

### Los cuatro campos que más se eligen mal

| Campo | En este ejemplo | De qué depende |
| - | - | - |
| `cbteTipo` | `6` = Factura B | Tu condición frente al IVA **y la de tu cliente**. Ver [comprobantes A, B y C](https://www.emissa.com.ar/docs/guias/tipos-de-comprobante.md) |
| `receiverDocTipo` | `99` = consumidor final | `80` es CUIT, `96` DNI. Con `99` el número del documento va en `"0"` |
| `receiverVatConditionId` | `5` = consumidor final | Obligatorio desde la RG 5616. `1` es responsable inscripto |
| `vatRateId` | `5` = 21 % | `4` es 10,5 %, `6` es 27 %, `3` es 0 %. **0 % no es exento ni no gravado** |

### La clave de idempotencia es obligatoria

> [!WARNING]
>
> Un comprobante fiscal duplicado **no se deshace**: se anula con una nota de
> crédito y las dos cosas quedan en tu historia y en la de ARCA. Por eso la
> clave es obligatoria y no un consejo.

Repetí el mismo pedido con la **misma** clave y no se emite un segundo: devuelve
el mismo comprobante, el mismo CAE y el mismo número, en 0,02 s en vez de 7,1
porque no sale a ARCA.

> [accordion] Qué pasa sin la clave, y qué pasa al repetir
>
> Sin el header:
>
> ```json theme={null}
> {
>   "statusCode": 400,
>   "errorCode": "IDEMPOTENCY_KEY_REQUIRED",
>   "message": "Falta el header Idempotency-Key. Es obligatorio en las operaciones que emiten un comprobante."
> }
> ```
>
> Repitiendo el mismo comando, sin cambiar nada:
>
> ```
> HTTP 201 · Idempotent-Replay: true · 0,02 segundos
> id devuelto: cms6l4gnq0007ur04xl1dcqf0 | cae: 86300696468093 | number: 131
> ```
>
> Verificado contando en la base: siguió habiendo **uno** con ese CAE.

## 3 · Consultar

```bash theme={null}
curl https://api.emissa.com.ar/v1/invoices/cms6l4gnq0007ur04xl1dcqf0 \
  -H "X-API-Key: $EMISSA_API_KEY" -i
```

```
HTTP 200 · 0,02 s
X-Request-Id: 17a81316-cd43-4f0f-b320-3c7a0e48ddfa
X-Emissa-Mode: test
```

> [!TIP]
>
> **Logueá esas dos cabeceras desde el primer día.** `X-Request-Id` identifica
> el pedido si tenés que reportar algo, y `X-Emissa-Mode` te dice si la clave
> que usaste es de prueba o productiva — lo segundo evita la clase de sorpresa
> que no se descubre hasta fin de mes.

## 4 · El PDF

```bash theme={null}
curl https://api.emissa.com.ar/v1/invoices/cms6l4gnq0007ur04xl1dcqf0/pdf \
  -H "X-API-Key: $EMISSA_API_KEY" -o comprobante.pdf
```

```
HTTP 200 · 0,08 s · 11696 bytes
```

Trae el bloque del emisor, el detalle, las leyendas de transparencia fiscal y el
QR de la RG 4892.

## 5 · Anular

En Argentina un comprobante autorizado **no se borra**: se anula emitiendo una
**nota de crédito** que lo referencia. Emissa lo hace en un pedido.

```bash theme={null}
curl -X POST https://api.emissa.com.ar/v1/invoices/cms6l4gnq0007ur04xl1dcqf0/cancel \
  -H "X-API-Key: $EMISSA_API_KEY" \
  -H "Idempotency-Key: quickstart-6.1-anular"
```

```
HTTP 200 · 0,35 s
tipo        : 8 NOTA_CREDITO_B (letra B)
comprobante : 0001-00000033
cae NC      : 86300696473229
status      : AUTHORIZED
total       : 1210.00
```

> [!NOTE]
>
> **La nota de crédito tiene su propio CAE**, distinto del de la factura: es un
> comprobante fiscal por derecho propio. Y la factura original conserva el suyo
> —fue válida y ARCA la autorizó— y ahora apunta a la nota que la anula.

## Cuánto tarda de verdad

Tiempos medidos en la corrida de arriba, en el orden en que se hicieron:

| Paso | Tiempo | Por qué |
| - | - | - |
| **Emitir** (primera vez) | **7,09 s** | Autentica contra ARCA y emite |
| Reintento idempotente | 0,02 s | No sale a ARCA: devuelve lo guardado |
| Consultar | 0,02 s | Lectura local |
| Bajar el PDF | 0,08 s | Se genera al pedirlo |
| Anular | 0,35 s | Emite con el ticket de ARCA ya en caché |

**Los cuatro pedidos suman menos de 8 segundos.** El primero paga la
autenticación contra ARCA, que dura 12 horas y queda cacheada: por eso anular
—que también sale a ARCA— tardó 0,35 s y no 7.

Si tu primera emisión tarda parecido, está bien.

## El error que casi todos cometen primero

La clave va en `X-API-Key`. En `Authorization` no funciona, y la API lo dice:

```json theme={null}
{
  "statusCode": 401,
  "errorCode": "API_KEY_WRONG_HEADER",
  "message": "Las API keys van en el header X-API-Key, no en Authorization. Usá: X-API-Key: emi_...",
  "details": "La key llego en Authorization; va en X-API-Key desde la version 1"
}
```

## Sobre el sandbox y producción

La clave de prueba opera contra **homologación**, y homologación **no consume
cuota**: después de emitir la factura y la nota de crédito, el consumo seguía en
cero — `total: 2` comprobantes, `billable: 0`.

> [!WARNING]
>
> **Leé esto antes de pasar a producción.** Emitir en `PRODUCCION` está
> habilitado, y lo que emitís ahí es un **comprobante fiscal real**. Entra en los
> registros del contribuyente ante ARCA, pesa en su declaración de IVA, y **no se
> borra** — se revierte con una nota de crédito.
>
> Todo lo que hiciste hasta acá fue en homologación, que emite con CAE real del
> organismo y **no** tiene consecuencia fiscal. Es el lugar para probar; no hay
> apuro en salir de ahí.

Lo que ARCA te va a exigir para producción, y que Emissa no verifica porque vive
del otro lado:

* Certificado productivo.
* Punto de venta de tipo «Factura Electrónica – Web Service» — uno de
  *Comprobantes en Línea* **no sirve**.
* El servicio autorizado.

Si falta alguno, contesta ARCA con el motivo concreto.

Los controles que **sí** hace Emissa, medidos: una clave de prueba contra un
contribuyente en producción devuelve `403`, y una productiva sin credencial
cargada devuelve `400`. Los dos conjuntos son disjuntos a propósito: **no podés
emitir un comprobante fiscal real con la clave con la que estabas probando**.

## Qué sigue

> [card] [Qué es un punto de venta](https://www.emissa.com.ar/docs/guias/punto-de-venta.md)
>
> El alta que hay que hacer en ARCA antes de emitir.

> [card] [Comprobantes A, B y C](https://www.emissa.com.ar/docs/guias/tipos-de-comprobante.md)
>
> Elegir mal el tipo es el rechazo más común.

> [card] [Cómo se numera una serie](https://www.emissa.com.ar/docs/guias/numeracion.md)
>
> Por qué un hueco importa.

> [card] [Referencia de la API](https://www.emissa.com.ar/docs/api-reference)
>
> El detalle de cada operación.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.