# Documentacion tecnica - API de Facturacion Electronica ZAMPHIROPOLOS

Este repositorio consolida la documentacion tecnica disponible para prospectos e integradores de facturacion electronica.

## Contenido

- [Portal HTML navegable](portal-documentacion/index.html): version visual y unificada para publicar en la nube.
- [Documentacion original](API-ZAMPHIROPOLOS): PDFs, planilla tecnica y ejemplos JSON provistos.
- [Ejemplos JSON](API-ZAMPHIROPOLOS/json%20ejemplos): casos de factura, nota de credito, nota de debito y nota de remision.

## Ejecucion local con Node

El portal no requiere dependencias externas. Desde la raiz del proyecto:

```powershell
npm start
```

Luego abrir:

```text
http://localhost:8080/portal-documentacion/
```

## Alcance funcional

La API permite operar documentos electronicos ante SIFEN mediante servicios para:

- Factura electronica.
- Nota de credito electronica.
- Nota de debito electronica.
- Autofactura electronica.
- Nota de remision electronica.
- Eventos, como cancelacion y nominacion.
- Consulta de documentos por CDC.
- Consulta de documentos por numero de comprobante.
- Obtencion de KUDE en PDF o base64.

## Estructura general del envio

Los documentos se envian como JSON. Cada payload usa una raiz segun el tipo de documento:

| Documento | Raiz JSON | Ejemplo |
| --- | --- | --- |
| Factura | `factura` | `venta al contado.json` |
| Nota de credito | `notaCredito` | `Json NC aso doc electronico.json` |
| Nota de debito | `notaDebito` | `Json ND.json` |
| Nota de remision | `notaRemision` | `Json NRE.json` |
| Autofactura | `autofactura` | Ver planilla tecnica y PDF correspondiente |

Bloques comunes:

- `datosGeneralesOperacion`: fecha, tipo de impuesto, presencia y transaccion.
- `datosTimbrado`: timbrado, establecimiento, punto de expedicion, numero y vigencia.
- `datosReceptor`: datos fiscales y comerciales del receptor.
- `itemsOperacion`: detalle de productos o servicios.
- `datosMonedaFactura`: moneda y tipo de cambio cuando corresponde.
- `camposTotales`: subtotales, impuestos, bases gravadas y total a pagar.
- `codigoActividadEconomica`: actividad economica declarada.

## Endpoints identificados

La documentacion original incluye servicios REST. Los endpoints que quedaron legibles en los PDFs son:

| Operacion | Metodo | Ruta |
| --- | --- | --- |
| Evento de cancelacion | `POST` | `/api/150/evento/cancelacion` |
| Evento de nominacion | `POST` | `/api/150/evento/nominacion` |
| Consulta por CDC | `GET` | `/api/consultas/de/{cdc}` |
| Consulta por comprobante | `GET` | `/api/consultas/documento-electronico?tipo={tipo}&establecimiento={est}&expedicion={punto}&documento={numero}` |

Los PDFs originales de envio asincrono contienen el detalle de los servicios de factura, nota de credito, nota de debito, autofactura, nota de remision y KUDE.

## Headers

Los servicios documentados usan encabezados como:

```http
Content-Type: application/json
Accept: */*
X-INSIFEN-EMISOR-ID: {emisor}
```

El valor real de `X-INSIFEN-EMISOR-ID`, la URL base, credenciales y restricciones de acceso deben ser entregados por ambiente.

## Publicacion privada en la nube

Para entregar esta documentacion a prospectos, se recomienda publicar el portal HTML en un hosting privado con autenticacion:

- Cloudflare Pages + Cloudflare Access.
- AWS S3/CloudFront + Cognito o reglas de acceso.
- Azure Static Web Apps con autenticacion.
- Netlify/Vercel con password protection o identidad corporativa.

La opcion mas simple para demos comerciales suele ser Cloudflare Pages con Cloudflare Access: se publica como sitio estatico y se habilita acceso por email para cada prospecto.

## Nota de mantenimiento

La fuente canonica sigue siendo `API-ZAMPHIROPOLOS/Doc Tecnica FE ZAM.xlsx` y los PDFs originales. Cuando cambien campos, endpoints o reglas de SIFEN, actualizar primero los anexos originales y luego este portal.