GRUPO ALCER, S.A. · API v1

Documentación de la API de facturación

Una API REST sobre HTTPS, con JSON de ida y de vuelta. Emite documentos electrónicos ante la SAT a nombre de tu empresa desde tu propio sistema. Tu credencial identifica a tu emisor: no tienes que mandar tu NIT ni tu token fiscal en cada llamada.

URL base https://facturacion.bitalcer.com/api/v1

Autenticación

Toda llamada lleva tu credencial en el encabezado Authorization. La generas en tu panel, en Configuración → Credenciales de API. Se muestra una sola vez: si la pierdes, generas otra y revocas la anterior. 

Authorization: Bearer ga_live_a1b2c3d4e5f6…
Accept: application/json
Content-Type: application/json
Tu credencial es un secreto.

Guárdala en el servidor, nunca en el navegador, en una aplicación móvil ni en tu repositorio. Puedes restringirla a las IP de tus servidores y revocarla desde el panel en cualquier momento. Si sospechas que alguien la vio, revócala: las facturas ya emitidas no se tocan.

Ambientes

PRUEBA ga_test_…

Todo funciona igual, pero nada llega a tu período fiscal. Úsalo hasta que tu sistema haga lo que esperas.

PRODUCCIÓN ga_live_…

Documentos reales ante la SAT. Consumen el cupo de tu plan y quedan en tu período. Cambias la credencial y nada más.

Idempotencia

Emitir no se puede deshacer, así que toda operación que emite acepta el encabezado Idempotency-Key. Manda ahí el identificador de la venta en tu sistema. Si tu proceso reintenta —porque se cayó la red, porque el usuario dio dos veces clic— recibes la misma factura, no una segunda. 

Idempotency-Key: venta-40192

La llave se recuerda 24 horas. Úsala una vez por venta, nunca reutilices la misma para dos ventas distintas: la segunda recibiría la factura de la primera.

POST /v1/facturas

Emitir una factura

El endpoint principal. Devuelve el documento ya firmado y certificado, con su número de autorización.

petición
{
  "receptor": {
    "nit": "1234567-8",
    "nombre": "CLIENTE DE EJEMPLO",
    "direccion": "Ciudad de Guatemala",
    "correo": "cliente@correo.com"
  },
  "establecimiento": 1,
  "items": [
    {
      "cantidad": 1,
      "descripcion": "Servicio de consultoría",
      "precio": 1500.00,
      "tipo": "S",
      "descuento": 0
    }
  ]
}
201 Created
{
  "id": "fac_01m2ygm4cb",
  "estado": "EMITIDO",
  "serie": "75489510",
  "numero": "1561742509",
  "numero_autorizacion":
    "75489510-5D16-4CAD-…",
  "fecha_emision":
    "2026-09-20T01:14:00-06:00",
  "total": 1500.00,
  "xml_url": "https://…/xml",
  "pdf_url": "https://…/pdf"
}

Campos

Campo Tipo Notas
receptor.nittextoNIT o CF. CF solo si el total es menor a Q2,500.00
receptor.nombretextoNombre fiscal. Si lo omites, lo consultamos con la SAT por ti
receptor.correotextoOpcional. Si viene, le mandamos el PDF a tu cliente
establecimientoenteroOpcional si tu emisor tiene uno solo
items[].cantidadnúmeroDe 0.01 a 999,999.99
items[].descripciontextoHasta 255 caracteres
items[].precionúmeroEn quetzales, IVA incluido
items[].tipotextoB bien · S servicio
fecha_emisionfechaOpcional. La SAT admite hasta 5 días hacia atrás

De 1 a 100 líneas por documento.

POST /v1/receptores/consultar

Consultar un NIT

A nombre de quién está un NIT según la SAT. Úsalo para validar el dato antes de cobrar, en vez de descubrir en la emisión que estaba mal escrito. 

{ "nit": "5487981" }

→ 200  { "encontrado": true,
         "nombre": "CLIENTE DE EJEMPLO",
         "cui": "" }
POST /v1/facturas/{id}/anular

Anular un documento

Anular no borra: el documento queda anulado y registrado en tu período fiscal, con su constancia. Consume una solicitud de tu cupo, igual que emitir. 

{ "observacion": "Cobro duplicado" }

→ 200  { "estado": "ANULADO",
         "anulado_en": "2026-09-20T09:12:00-06:00" }
GET /v1/facturas

Listar documentos

Lo que has emitido, con filtros y paginado. Es lo que tu contador necesita para cuadrar el mes sin pedirte nada.

desde=2026-09-01 hasta=2026-09-30 estado=VIGENTE nit_receptor=1234567-8 pagina=1
GET /v1/facturas/{id}/pdf · /xml

Descargar PDF y XML

El documento firmado, tal como lo recibe tu cliente, y el XML para tu contabilidad. Los enlaces que devuelve la emisión caducan; estos endpoints funcionan siempre.

Errores

Todos los errores traen un codigo estable y un mensaje escrito para que se lo puedas enseñar a una persona.

HTTP Código Qué hacer
401credencial_invalidaRevisa la llave, el ambiente y la restricción por IP
422datos_invalidosEl mensaje dice qué campo. Corrige y reintenta
422cf_no_permitidoEl total llega a Q2,500: pide el NIT a tu cliente
409llave_ya_usadaEsa Idempotency-Key ya emitió. Te devolvemos esa factura
429cupo_agotadoLlegaste al tope del mes. Sube de plan desde tu panel
504resultado_inciertoNo reintentes a ciegas. La SAT no contestó y el documento pudo firmarse. Consulta antes

Reglas de la SAT que conviene tener presentes

CF hasta Q2,500

De ahí en adelante hace falta el NIT del receptor. La API lo rechaza antes de emitir.

Cinco días hacia atrás

Es lo que admite la SAT en fecha_emision. Más atrás, sale con la fecha de hoy.

Anular no borra

El documento queda en tu período como anulado. No hay forma de hacerlo desaparecer.

Cupo del plan

Cada emisión y cada anulación consume una solicitud. Toda respuesta trae cuántas te quedan, para que tu sistema pueda avisar antes de quedarse sin cupo. 

X-Cupo-Limite: 833
X-Cupo-Restante: 614
X-Cupo-Renueva: 2026-10-01

¿Algo no cuadra?

Escríbenos con el id de la factura o tu Idempotency-Key. Con eso lo encontramos en segundos. Nunca nos mandes tu credencial, ni siquiera un pedazo: no la necesitamos para ayudarte.

Teléfono / WhatsApp