abnlookup

hyraiq/abnlookup

Un SDK de PHP para validar números comerciales australianos (ABN) y verificarlos con la API de servicios web del Registro Comercial Australiano. La diferencia entre validación y verificación se puede resumir de la siguiente manera:

• La validación utiliza el cálculo de la suma de verificación oficial para verificar que un número determinado sea un ABN válido. Esto no contacta al ABR para garantizar que el ABN dado esté asignado a una empresa.
• Verificación contacte a la ABR a través de su API para recuperar la información registrada en la ABN. Le dirá si el ABN realmente pertenece a una empresa.

Para utilizar la API (solo es necesaria para la verificación), deberá registrar una cuenta para recibir un GUID que se utiliza como clave API. Una vez que te registres podrás jugar con la API usando la demostración oficial (ten en cuenta que este SDK utiliza los servicios JSON en lugar de XML).

Tipo de seguridad

El SDK utiliza Symfony Serializer y Symfony Validator para deserializar y validar los datos devueltos por la API ABR con el fin de proporcionar modelos AbnResponse y NamesResponse válidos. Esto significa que si recibe una respuesta del SDK, se garantiza que será válida.

Las respuestas no válidas del ABR se dividen en tres categorías, que se manejan con excepciones:

• AbrConnectionException : no se puede conectar al ABR o el ABR devolvió una respuesta inesperada
• InvalidAbnException : el ABN no es válido (es decir, la validación falló)
• AbnNotFoundException : el ABN es válido, sin embargo, no está asignado a una empresa (es decir, la verificación falló)

Uso

Instalación

$ composer require hyraiq/abnlookup

Configuración con Symfony

En services.yaml , debe pasar su GUID ABR a AbnClient y registrar AbnClient con AbnClientInterface :

 HyraAbnLookupAbnClientInterface : ' @HyraAbnLookupAbnClient '
HyraAbnLookupAbnClient :
    arguments :
        $abnLookupGuid : " %env(ABN_LOOKUP_GUID)% "

Luego puede inyectar AbnClientInterface directamente en sus controladores/servicios.

 class VerifyAbnController extends AbtractController
{
    public function __construct (
        private AbnClientInterface $ abnClient ,
    ) {
    }
    
    // ...  
}

Configuración fuera de Symfony

Si no estás usando Symfony, necesitarás crear una instancia del cliente ABN tú mismo, que puedes registrar en tu contenedor de servicios o simplemente usarlo directamente. Hemos proporcionado algunos ayudantes en la clase Dependencies para crear el Serializador y Validador de Symfony con opciones mínimas.

 use Hyra  AbnLookup  Dependencies ;
use Hyra  AbnLookup  AbnClient ;

$ abrGuid = ' <insert your ABR GUID here> '

// Whichever http client you choose
$ httpClient = new HttpClient ();

$ denormalizer = Dependencies :: serializer ();
$ validator = Dependencies :: validator ();

$ abnClient = new AbnClient ( $ denormalizer , $ validator , $ httpClient , $ abrGuid );

Buscando un ABN

Una vez que haya configurado su AbnClient puede buscar un ABN individual. Tenga en cuenta que esto validará el ABN antes de llamar a la API para evitar solicitudes de API innecesarias.

 $ abn = ' 12620650553 ' ;

try {
    $ abnResponse = $ abnClient -> lookupAbn ( $ abn );
} catch ( AbrConnectionException $ e ) {
    die ( $ e -> getMessage ())
} catch ( InvalidAbnException ) {
    die ( ' Invalid ABN ' );
} catch ( AbnNotFoundException ) {
    die ( ' ABN not found ' );
}

echo $ abnResponse -> abn ; // 12620650553
echo $ abnResponse -> entityName ; // Blenktech PTY LTD
echo $ abnResponse -> status ; // Active

Buscando por nombre

También puede buscar en la ABR por nombre, para recibir una lista de negocios registrados que coinciden con el término de búsqueda:

 $ namesResponse = $ abnClient -> lookupName ( ' Hyra iQ ' );

echo sprintf ( ' Received %d results ' , count ( $ namesResponse -> names ));
foreach ( $ namesResponse -> names as $ name ) {
    echo sprintf ( ' %s: %s ' , $ name -> abn , $ name -> name );
}

Pruebas

En las pruebas automatizadas, puede reemplazar AbnClient con StubAbnClient para simular respuestas del ABR. También existe AbnFaker que puede utilizar durante las pruebas para obtener ABN válidos e inválidos.

 use Hyra  AbnLookup  Stubs  AbnFaker ;
use Hyra  AbnLookup  Stubs  StubAbnClient ;

$ stubClient = new StubAbnClient ();

$ stubClient -> lookupAbn ( AbnFaker :: invalidAbn ()); // InvalidAbnException - Note, the stub still uses the validator

$ stubClient -> lookupAbn ( AbnFaker :: validAbn ()); // LogicException - You need to tell the stub how to respond to specific queries

$ abn = AbnFaker :: validAbn ();
$ stubClient -> addNotFoundAbns ( $ abn );
$ stubClient -> lookupAbn ( $ abn ); // AbnNotFoundException

$ abn = AbnFaker :: validAbn ();
$ mockResponse = new AbnResponse ();
$ response -> abn = $ abn ;
$ response -> abnStatus = ' active ' ;
$ response -> abnStatusEffectiveFrom = new  DateTimeImmutable ( ' 2 years ago ' );
$ response -> entityTypeCode = ' PRV ' ;
$ response -> entityTypeName = ' Australian Private Company ' ;

$ stubClient -> addMockResponse ( $ mockResponse );
$ abnResponse = $ stubClient -> lookupAbn ( $ abn ); // $abnResponse === $mockResponse 

Contribuyendo

¡Todas las contribuciones son bienvenidas! Necesitará tener instalada la ventana acoplable para poder ejecutar pruebas y procesos de CI localmente. Estos también se ejecutarán en su solicitud de extracción y las fallas se agregarán como anotaciones de GitHub en la vista Archivos.

 # First build the required docker container
$ docker compose build

# Then you can install composer dependencies
$ docker compose run php ./composer.phar install

# Now you can run tests and other tools
$ docker compose run php make (fix | psalm | phpstan | phpunit)

Para que su PR sea aceptado, deberá estar cubierto por pruebas y ser aceptado por:

• reparador de php-cs
• salmo
• phpstan