Codex/importacion fiscal historica

README.md

@@ -10,13 +10,13 @@ de errores HTTP y la descarga de documentos.
 | Componente | Versión usada |
 | --- | --- |
 | Módulo Go | `v2` (`github.com/unkcode-org/gofip-sdk-go/v2`) |
-| API GOFIP | `2.18.0` y rutas bajo `/api/v2` |
+| API GOFIP | `2.19.0` y rutas bajo `/api/v2` |
 | Especificación OpenAPI | `3.0.3` |
 | Go | `1.22.2` o posterior |
 
 El contrato HTTP de referencia está en
 [`docs/openapi.yaml`](docs/openapi.yaml). Los campos `openapi: 3.0.3` e
-`info.version: "2.18.0"` indican, respectivamente, la versión del formato OpenAPI
+`info.version: "2.19.0"` indican, respectivamente, la versión del formato OpenAPI
 y la versión del contrato de la API. No deben confundirse con una versión
 publicada del módulo Go.
 
@@ -27,6 +27,7 @@ publicada del módulo Go.
   comprobante, opcionales, tipos de documento, monedas y cotizaciones.
 - Consultas de padrón P4, P5, P10 y P13.
 - Emisión de facturas y consulta de comprobantes.
+- Importación fiscal histórica verificada de GOFIP Legacy, con API key normal del mismo emisor/PV.
 - Generación y descarga de comprobantes, facturas y recibos en PDF.
 - Errores tipados para respuestas de la API y respuestas HTTP no estructuradas.
 - Cliente HTTP y URL base configurables.
@@ -335,7 +336,10 @@ no comprueba la existencia del objeto remoto ni genera una URL firmada.
 
 **Ambiente:** GOFIP no persiste el ambiente en Documento/Factura. Estas consultas
 no envían `X-ARCA-Ambiente` y no filtran por homologación/producción. Los registros
-exclusivos de Legacy requieren una migración de datos independiente.
+exclusivos de Legacy se incorporan mediante `ImportarFactura`, previa verificación
+obligatoria en ARCA Producción y API key normal del mismo emisor/PV. Ver
+[importación histórica](docs/importacion-facturas.md) para modelos, uso, errores,
+idempotencia y límites de PDF. No hay batch ni emisión como fallback.
 
 ## Integraciones SEP: un cliente y una credencial distintos
 
@@ -408,6 +412,6 @@ go test -race ./...
 ```
 
 Ver [arquitectura](docs/arquitectura.md) y [validación manual](docs/validacion.md).
-El contrato de referencia es OpenAPI 2.18.0 del backend. No se publica una versión
+El contrato de referencia es OpenAPI 2.19.0 del backend. No se publica una versión
 como parte de estas pruebas. La secuencia prevista es `v2.0.0-rc.1` → `v2.0.0`,
 con imports `/v2`, validación externa y aprobación de publicación.

contrato_importacion_test.go

@@ -0,0 +1,40 @@
+package gofip
+
+import (
+	"crypto/sha256"
+	"fmt"
+	"os"
+	"reflect"
+	"regexp"
+	"strings"
+	"testing"
+
+	"github.com/unkcode-org/gofip-sdk-go/v2/modelos/facturacion"
+)
+
+func TestContratoImportacionYProcedenciaExacta(t *testing.T) {
+	yaml, err := os.ReadFile("docs/openapi.yaml")
+	if err != nil {
+		t.Fatal(err)
+	}
+	provenance, err := os.ReadFile("docs/CONTRATO.md")
+	if err != nil {
+		t.Fatal(err)
+	}
+	hash := fmt.Sprintf("%x", sha256.Sum256(yaml))
+	if !strings.Contains(string(provenance), hash) || !strings.Contains(string(provenance), "Versión: 2.19.0.") {
+		t.Fatal("copia OpenAPI sin procedencia o checksum actualizado")
+	}
+	for _, token := range []string{`version: "2.19.0"`, "/api/v2/facturas/importaciones:", "mismo emisor y punto de venta", "emisor_id+credencial_id+punto_venta_id", "legacy_import", "SolicitudImportarFactura:", "RespuestaImportarFactura:", "DecimalHistorico:", "VerificacionImportacion:", "CompletitudDocumental:"} {
+		if !strings.Contains(string(yaml), token) {
+			t.Fatalf("contrato sin %s", token)
+		}
+	}
+	for _, typ := range []reflect.Type{reflect.TypeOf(OpcionesImportacionFactura{}), reflect.TypeOf(facturacion.SolicitudImportarFactura{}), reflect.TypeOf(facturacion.FacturaHistorica{})} {
+		for i := 0; i < typ.NumField(); i++ {
+			if regexp.MustCompile(`(?i)ambiente|emisor`).MatchString(typ.Field(i).Name) {
+				t.Fatalf("%s amplía autoridad", typ)
+			}
+		}
+	}
+}

docs/CONTRATO.md

@@ -2,13 +2,14 @@
 
 - Repositorio canónico: unkcode-org/gofip-backend.
 - Archivo: backend/docs/openapi.yaml.
-- Versión: 2.18.0.
-- Commit de implementación: ed68c3a3e0e664e8b8ebeda7a8fff20eb1b60aea.
-- Base auditada de develop: 12581b385b4fc7321334e4442493ef0159f8a612.
-- SHA-256 de los bytes YAML copiados: 90d2171d496a0984e80e835fdfa86ee124bfeee49d472d2d8d74bb02467021e4.
+- Versión: 2.19.0.
+- Commit de implementación: 7918e9d373a8cbc298258cb9314d5d33e54d38b3.
+- Base auditada de develop: ea7beffef41a91e548a1e7b8ed17e388fdd948da.
+- SHA-256 de los bytes YAML copiados: 82ed564929b6c46e608d7922dc0a4fb93e1f4e1c2d8ec7bc06d434b4975d92b1.
 
-La copia se verificó byte a byte. El formato del SDK local anterior se respaldó
-antes de reemplazarlo; sus rutas y schemas se habían contrastado con el backend.
-Para actualizar, editar primero el contrato canónico, su versión y changelog;
-verificar el backend y copiar el archivo exacto al SDK. No editar esta copia como
-fuente independiente. El commit de implementación todavía no implica un despliegue.
+La copia se verificó byte a byte después de estabilizar Backend/OpenAPI. Incluye
+importación Legacy verificada en Producción y no agrega ambiente a documentos o
+identidad fiscal. Para actualizar, editar primero el contrato canónico, su versión
+y changelog; verificar el backend y copiar el archivo exacto al SDK. No editar
+esta copia como fuente independiente. El commit de implementación no implica un
+despliegue, release ni importación real.

docs/arquitectura.md

@@ -9,6 +9,7 @@ dependencias ni se modifica la semántica del transporte anterior.
 
 | Operación | Fuente | Cliente |
 | --- | --- | --- |
+| ImportarFactura | FECompConsultar Producción → persistencia; API key normal del mismo emisor/PV | Bearer |
 | EmitirFactura | GOFIP → ARCA, persistencia | Bearer |
 | ObtenerComprobante | Consulta directa a ARCA | Bearer |
 | ObtenerFacturaPorCAE / ObtenerFacturaPorId | MySQL exclusivamente | Bearer |
@@ -24,8 +25,8 @@ Los modelos fiscales persistidos tienen identidad distinta del comprobante ARCA:
 incluyen documento/factura ID, estado GOFIP, ítems guardados y metadata PDF. Las
 consultas por CAE e ID comparten `RespuestaFacturaPersistida`. No se recuperan datos
 desde Legacy, ARCA o entidades mutables como fallback. No existe filtro de ambiente
-porque el modelo actual no persiste ese dato. No se agregan migraciones ni índices
-únicos de CAE. Un CAE ambiguo produce 409 y admite filtros explícitos.
+porque el modelo actual no persiste ese dato. La importación agrega identidad fiscal compartida por emisor/PV/tipo/número,
+sin índice único de CAE. Un CAE ambiguo produce 409 y admite filtros explícitos.
 
 SEP nunca guarda cookies de navegador ni hace intercambio de bootstrap. Sus
 respuestas contienen capacidades de corta duración con acceso explícito mediante
@@ -37,3 +38,7 @@ El contrato canónico se mantiene en `backend/docs/openapi.yaml` de gofip-backen
 `docs/openapi.yaml` es una copia exacta. Cada cambio debe comenzar en el backend,
 incrementar su versión y changelog y luego sincronizar esta copia. El SDK conserva
 el módulo `/v2` y Go mínimo 1.22.2.
+
+La importación usa un transporte con redacción de errores y sin retries ni
+redirecciones. Su configuración no acepta ambiente y no modifica el transporte
+de emisión. Ver [importación histórica](importacion-facturas.md).