Bearer token

Headers (rutas protegidas)

Authorization: Bearer <token_de_acceso>
Content-Type: application/json
Accept: application/json

Dónde obtener el token

1. Alta de integrador → token maestro (correo + respuesta JSON)
2. Crear empresa POST /api/ubl2.1/config/{nit} → token de esa empresa
3. Panel web de la empresa (api_token)
4. Login API (abajo)

Importante: El token de Sandbox no funciona en Producción. Usa el host correcto: Ambientes.

Login API

POST /api/login
Content-Type: application/json

{
  "email": "usuario@empresa.com",
  "password": "tu_password"
}

La respuesta incluye el api_token para usar como Bearer. Útil si tu app no guarda el token del alta.

Token maestro vs token de empresa

Token	Sirve para
Maestro (integrador)	Crear NITs, comprar cupo, ver plan
Empresa (NIT)	Emitir FE, NC, nómina, RADIAN, RIPS, etc. de ese NIT

Rutas sin Bearer (públicas / especiales)

No todo /api exige token. Ejemplos:

Ruta	Uso
GET /api/ubl2.1/environment	Identificar Sandbox/Prod
POST /api/ubl2.1/integrators/register	Alta self-serve
GET /api/ubl2.1/grid-pay/products	Catálogo FACT-E
POST /api/login	Obtener token
GET /api/ubl2.1/listing	Listados auxiliares

El resto de emisión/configuraión sí requiere Bearer.

Ejemplo cURL (Sandbox)

curl -sS https://sandbox-api.gridbilling.gridsoft.co/api/ubl2.1/environment \
  -H "Accept: application/json"

curl -sS https://sandbox-api.gridbilling.gridsoft.co/api/ubl2.1/invoice/{testSetId} \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d @invoice.json

Buenas prácticas

• Un token por empresa / integración
• Nunca en frontends públicos ni repos
• Rota el token si se filtra
• Solo HTTPS

Errores comunes

Síntoma	Causa
401	Token vacío, mal formado o de otro host
422	Body incompleto (no es auth)
CSRF en /login web	Eso es el panel, no POST /api/login

La API REST no usa sesión web ni CSRF; solo Bearer (salvo rutas públicas).

→ Respuestas y errores