API Reference

Clientes (personas/empresas)

El directorio de clientes es opcional: la factura lleva los datos del comprador inline (ver Facturas). Este recurso te sirve para mantener un maestro normalizado de personas y empresas, con lookup en línea al catastro del SRI.

Listar clientes

GET /api/v1/personas-empresas — Lista las personas/empresas de tu directorio

Query params

Parámetro	Tipo	Descripción
`q` optional	string	Búsqueda por identificación o razón social.

Buscar por RUC o cédula (lookup SRI)

GET /api/v1/personas-empresas/lookup/{identificacion} — Primero busca en tu directorio; si no está, consulta el catastro del SRI

Si el cliente existe en tu directorio, lo devuelve con fuente: "LOCAL". Si no, hace un lookup en tiempo real contra el catastro público del SRI (fuente: "SRI") y te devuelve los datos prellenados, listos para guardar con un POST.

{
  "identificacion": "0991234567001",
  "tipo_identificacion": "04",
  "razon_social": "ACME S.A.",
  "nombre_comercial": "ACME",
  "estado_contribuyente": "ACTIVO",
  "tipo_contribuyente": "SOCIEDAD",
  "direccion": "Av. Amazonas N35-17 y Juan Pablo Sanz",
  "encontrado": true,
  "fuente": "SRI",
  "mensaje": null
}

Crear un cliente

POST /api/v1/personas-empresas — Persiste una persona/empresa en tu directorio

Body

Parámetro	Tipo	Descripción
`tipo_identificacion` required	string	'04' RUC, '05' cédula, '06' pasaporte, '08' id. del exterior.
`identificacion` required	string	RUC (13 dígitos), cédula (10) o documento según el tipo.
`razon_social` required	string	Nombre o razón social. Máx 300 caracteres.
`nombre_comercial` optional	string	Nombre comercial.
`email` optional	string	Email para envío del RIDE.
`telefono` optional	string	Teléfono de contacto.
`direccion` optional	string	Dirección.
`es_cliente` optional	boolean	Marca como cliente. Default: true.
`es_proveedor` optional	boolean	Marca como proveedor (para retenciones). Default: false.

import { Emitoo } from "emitoo";

const client = new Emitoo(); // lee la API key de EMITOO_API_KEY

const cliente = await client.personasEmpresas.crear({
  tipo_identificacion: "04",
  identificacion: "0991234567001",
  razon_social: "ACME S.A.",
  email: "facturacion@acme.example",
  direccion: "Av. Amazonas N35-17",
});

from emitoo import EmitooClient

client = EmitooClient()  # lee la API key de EMITOO_API_KEY

cliente = client.personas_empresas.crear({
    "tipo_identificacion": "04",
    "identificacion": "0991234567001",
    "razon_social": "ACME S.A.",
    "email": "facturacion@acme.example",
    "direccion": "Av. Amazonas N35-17",
})

client, err := emitoo.New("") // lee la API key de EMITOO_API_KEY
if err != nil {
	log.Fatal(err)
}
ctx := context.Background()

cliente, err := client.PersonasEmpresas.Crear(ctx, emitoo.M{
	"tipo_identificacion": "04",
	"identificacion":      "0991234567001",
	"razon_social":        "ACME S.A.",
	"email":               "facturacion@acme.example",
	"direccion":           "Av. Amazonas N35-17",
})
if err != nil {
	log.Fatal(err)
}

curl -X POST https://api.emitoo.io/api/v1/personas-empresas \
  -H "X-API-Key: $EMITOO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo_identificacion": "04",
    "identificacion": "0991234567001",
    "razon_social": "ACME S.A.",
    "email": "facturacion@acme.example",
    "direccion": "Av. Amazonas N35-17"
  }'

Obtener un cliente

GET /api/v1/personas-empresas/{id} — Detalle de una persona/empresa por su id

Actualizar un cliente

PUT /api/v1/personas-empresas/{id} — Reemplaza los datos del cliente

El body es el mismo del POST (más activo): envía el objeto completo con los valores finales.

Eliminar un cliente

DELETE /api/v1/personas-empresas/{id} — Elimina el cliente del directorio (204)

Las facturas ya emitidas no se ven afectadas: llevan su propio snapshot de los datos del comprador al momento de la emisión.