API Go

Convenciones

Todos los endpoints comparten autenticación, envoltura de error, paginación y el modo de nombrar la unidad de negocio. Conviene leer esto antes que los endpoints.

URL base

El host identifica a la empresa (multi-tenant). Todo cuelga de /api/go/v1.

https://{empresa}.gosoft.app/api/go/v1/contratos
https://{empresa}.gosoft.app/api/go/v1/recibos
https://{empresa}.gosoft.app/api/go/v1/unidades
https://{empresa}.gosoft.app/api/go/v1/inmuebles

Autenticación

Cada llamada lleva un token Bearer. La empresa lo emite desde GoSoft para la persona que representa al sistema externo (Personal → Acceso GoSoft → Acceso a la API) y entrega un PDF con las credenciales. Es una cadena de 64 caracteres hexadecimales y no vence. Si se filtra, la empresa lo rota y el anterior deja de servir en el acto.

Authorization: Bearer 3f9c1e0b7a2d4c8e6f5a9b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e

Envoltura de respuesta

A diferencia de la API Multi Pagos, acá el status HTTP es real: 200 es éxito y cualquier otro es error. El éxito devuelve el objeto pedido directamente, sin envoltura. El error trae un codigo estable para ramificar; el mensaje es para humanos y puede cambiar de redacción.

{
  "codigo": 6557,
  "unidad": { ... },
  "estado": { ... }
  // el objeto, tal cual
}

{
  "error": {
    "codigo": "RANGO_EXCEDIDO",
    "mensaje": "El rango no puede superar 31 días; se pidieron 45."
  }
}

La unidad de negocio

Toda consulta lleva ?unidad=. El código es el mininame de la unidad seguido de su id, con guión: VALL1-7. Se aceptan además las variantes VALL17, VALL1 y 7; si el mininame no corresponde al id (VALL1-1) la unidad no existe.

Cabeceras

Paginación (endpoints 02, 04 y 06)

Flujo de integración

No hay handshake: con el token y el código de unidad se consulta directo.

Webhook de estados

GoSoft avisa al sistema externo cuando un inmueble de sus unidades cambia de estado (se reserva, se vende, se finaliza, se revierte o se anula). Se configura en GoSoft, en la misma persona del token: Personal → Acceso GoSoft → Acceso a la API → Webhook. La URL y el secreto de firma salen en el PDF de credenciales.

{
  "evento": "inmueble.estado",
  "entrega": 812,
  "fecha": "2026-10-22T16:44:30-04:00",
  "empresa": "zabdiel.gosoft.app",
  "unidad": { "codigo": "TERRA-6", "nombre": "TERRANOVA" },
  "inmueble": {
    "id": 2933, "codigo": "TN-A1", "proyecto": "TERRANOVA",
    "manzano": "A", "numero": "1", "piso": null, "complemento": null
  },
  "estado_anterior": "libre",
  "estado": "reservado",
  "inventario": { "total": 270, "libres": 7, "reservados": 2, ... }
}

$cuerpo = file_get_contents('php://input');
preg_match('/t=(\d+),v1=([a-f0-9]+)/',
  $_SERVER['HTTP_X_GOSOFT_FIRMA'], $m);
$ok = hash_equals(
  hash_hmac('sha256', $m[1] . '.' . $cuerpo, SECRETO),
  $m[2]
) && abs(time() - (int) $m[1]) < 600;

Inicio de sesión único

El personal entra a su panel con su usuario de GoSoft, sin otra contraseña. Hay dos formas; la empresa elige una en la persona del token y los datos salen en el PDF de credenciales. Una persona deshabilitada en GoSoft deja de poder entrar.

Opción A · OpenID Connect

Opción B · Enlace firmado

En GoSoft aparece Ir al panel web en el menú del usuario. Abre <url-del-panel>?token=<JWT>: RS256, firmado con la misma llave de /oauth/jwks, vence a los 60 segundos y su jti debe aceptarse una sola vez. aud es el origen del panel.

Datos de la persona (las dos opciones)

{
  "sub": "286",                     // id estable de la persona en la empresa
  "name": "ALEXANDER ALVAREZ",
  "preferred_username": "alexanderav286",
  "email": "persona@empresa.com",
  "rol": "administrador",           // administrador (nivel 4) o editor
  "nivel": 4,
  "activo": true,
  "empresa": "CONSTRUCTORA ZBL"
}

Ambiente de pruebas

La empresa demo https://inmobiliaria.gosoft.app, con datos de prueba. Cada integración tiene ahí sus propios accesos, que salen en el PDF de credenciales: token de API, usuario de prueba y, con OpenID Connect, su propio client_id. Los avisos del webhook de la demo llegan a la misma URL y con el mismo secreto.

curl "https://inmobiliaria.gosoft.app/api/go/v1/unidades" \
  -H "Authorization: Bearer <token de pruebas>"

Tabla de errores

El status HTTP es real. El codigo es estable; el mensaje puede cambiar de redacción.

Reglas de negocio

Decisiones del lado de GoSoft que explican por qué los números son los que son.

El precio del contrato

El precio no se toma del importe guardado en la cabecera del contrato, que en algunos registros históricos está duplicado. Se recalcula igual que la ficha: superficie por precio unitario del detalle de construcción, menos el descuento negociado al firmar. Es la misma fórmula de las auditorías y de los reportes de saldos, así que monto_final coincide con lo que ve el operador en pantalla.

La unidad de un recibo es la de su terreno

Un cobro puede haberse registrado estando parado en otra unidad de negocio, y la unidad que quedó grabada en el comprobante es la equivocada. Por eso unidad del recibo, y el filtro ?unidad= de los endpoints 03 y 04, salen del lote que se vendió y no del comprobante. Es la regla que hace que un recibo aparezca siempre donde está su contrato.

Los anulados se listan, no suman

pagos.total y pagos.cantidad cuentan sólo recibos vigentes; los anulados se listan aparte en anulados y vienen en items[] con su bloque anulacion. Un cobro revertido es información, pero no es plata que entró.

La cuenta contable del recibo

cuenta es el lado debe del asiento del comprobante: la caja o el banco donde entró el dinero, con su código del plan de cuentas. Se conserva también en los recibos anulados, porque la cuenta por la que pasó la plata sigue siendo un dato aunque el cobro se haya revertido. Un recibo tiene una sola cuenta; si alguna vez hay varias, aparecen todas en cuentas[] con su importe.

Claves que aparecen sólo cuando hace falta

La respuesta normal no trae ninguna de las tres. El mapeo del ERP debe tolerar su ausencia y su presencia.

El inventario

Un inmueble es cada lote o departamento vendible de los proyectos de la unidad (no cuentan los pisos ni el proyecto mismo). Su estado sale del contrato activo que lo ocupa: reserva, vigente o finalizado; sin ninguno está libre, salvo que esté marcado como “no vender”. Cada inmueble cae en un solo estado, así que las cifras siempre suman el total. Los números se calculan en el momento de la consulta.

Rango de un mes

Los endpoints por período aceptan hasta 31 días, contados en días y no en meses de calendario: del 1 al 31 de agosto entra, del 1 de junio al 15 de julio no. El tope existe para que una consulta no barra el histórico entero; para cargar años anteriores se recorre mes a mes.

Recomendaciones de integración

• Manda el token en la cabecera Authorization, nunca en la URL.
• Guarda recibo y contrato_nro como llaves: son los números que aparecen en los reportes contables del cliente.
• Para conciliar un mes, pide los recibos por período sin filtrar estado: así las anulaciones posteriores también se reflejan al re-sincronizar.
• Mapea estado.nombre del contrato por tabla y avisa si llega un valor nuevo.
• Trata el 401 por status HTTP; su cuerpo tiene otra forma.
• Ante un 500 o un timeout, reintenta: la API no escribe nada.